Data Groups

With few exceptions, data groups must be defined in a device template file in order for them to be available for use on a remote device. Which data groups are defined by a device template file depends on protocol, device type, and unique configuration.

CygNet distributes sample device template files for its EIEs, each of which typically serves one or more hardware models along with applicable firmware. Therefore, the data groups described in the table below are only those data groups defined by CygNet in sample device template file(s). Your template(s) might not include some of the data groups described below. Device template files exist to enable users to customize device configurations; however, CygNet is not responsible for changes made by users.

For information about data group definitions and device template files, see Device Template Files.

IoT Sparkplug EIE Data Groups

Data Group Type Usage Notes

CmdDev

The "Command - Device" data group writes a value to a device-level MQTT topic.

See Command-Type Data Groups.

CmdNode

The "Command - Edge Node" data group writes a value to a node-level MQTT topic.

See Command-Type Data Groups.

CfgDg

The "Configurable Data Group" data group provides a flexible way to create custom data groups on a per-device basis. See Configurable Data Group.

DynaCard

The "Dynagraph Card" data group enables the retrieval of dynagraph card data that corresponds to a subscription to an MQTT topic. See Dynagraph Card Data Group.

Topic1

"Topic 1" is a sample data group demonstrating how to set up a data group.

Data Group Properties

In the IoT Sparkplug EIE, each data group corresponds to a subscription to an MQTT topic. IoT Sparkplug EIE data groups include properties and fields specific to the IoT Sparkplug device.

Note: The IoT Sparkplug  EIE "Dynagraph Card" (DynaCard) data group requirements differ slightly from other data group types. For more information, see Dynagraph Card Data Group.

IoT Sparkplug EIE Data Group Properties

IoT Sparkplug EIE Data Group Properties

IoT Sparkplug Data Group Properties

The following table lists and describes properties specific to the IoT Sparkplug EIE Data Group Properties dialog page. See Dynagraph Card Data Group for specific requirements for DynaCards.

Property Description
Topic

Group ID

A Sparkplug topic Group ID is a logical grouping of MQTT Edge of Network (EoN) nodes into the MQTT server and back out to the subscribing clients.

Edge node ID

A Sparkplug topic Edge node ID uniquely identifies the MQTT Edge of Network (EoN) node within the infrastructure.

Device ID

A Sparkplug topic Device ID is an optional field entered by the user that identifies a device attached to the MQTT EoN node.

For more information, see Topic Options for Data Group Properties.

QoS

The Quality of Service. When Use comm default is unchecked, the data group uses the QoS (Quality of Service) value entered in this field.

QoS options are:

  • 0 (message delivered to the server at most once)
  • 1 (message delivered to the server at least once)
  • 2 (message delivered to the server exactly once)

Use comm default

When checked, the data group uses the Default QoS value specified in the device editor of the associated MQTT comm device.

When unchecked, the data group uses the value specified in the QoS field of the Data Group Properties dialog box.

For more information, see MQTT Comm EIE.

Payload format

The format of the payload data.

Options are:

  • JSON
  • Protobuf

Topic Options for Data Group Properties

IoT Sparkplug EIE non-DynaCard data groups can subscribe to either node level or device-level topics. In the Topics section of the Data Group Properties dialog:

Note: For IoT Sparkplug EIE DynaGraph Card Data Group requirements, see Dynagraph Card Topic Requirements.

Point Processing

The following information describes point processing for the IoT Sparkplug EIE and the IoT CygNet Link EIE. Message and data processing is handled in the same way on both EIEs.

Compression

The EIE supports reading compressed or uncompressed Sparkplug B payloads, including Sparkplug-formatted DynaCards, published from Link. It supports gzip and zlib data compression formats.

Alias Support

The EIE supports the use of optional aliases for Sparkplug metric names, which reduces overall message size for MQTT subscriptions.

When a payload on a birth message is received, each "metric" (the data item in the payload) can have an optional alias assigned. This is to reduce the number of bytes on future data payloads. For example, a metric name could equal "flow_meter_4_differential_pressure-northern_lot_5428_section2" with alias "2004" (representing a significant fewer number of bytes on every published payload). Optional aliases are supported in both templated and configurable data groups.

An alias is an unsigned 64-bit integer representing an optional alias for a Sparkplug B payload. If supplied in an NBIRTH or DBIRTH it must be a unique number across this EoN node's entire set of metrics. In other words, no two metrics for the same EoN node can have the same alias. Upon being defined in the NBIRTH or DBIRTH, subsequent messages can supply only the alias instead of the metric friendly name to reduce overall message size.

Timestamps

A payload file may include a timestamp for each data item, a timestamp for the entire payload, or no timestamp at all. When processing points, CygNet will assign timestamps in this order:

  1. the timestamp associated with the data item if it exists.
  2. the timestamp for the payload if it exists.
  3. the current time.

The timestamp locations are defined in the Sparkplug specification.

Lost Connection

When payload data indicates the connection between the MQTT server and the remote device has been lost, CygNet can be configured to set all points associated with the topic to unreliable. This feature is enabled in the device template file for each data group using the setUnreliableOnLostConnection attribute. If true, all CygNet points associated with the topic are set to unreliable. Otherwise the point status is unchanged.

The Sparkplug node and device DEATH messages are used to indicate a lost connection.

ReBIRTH Request

The EIE driver automatically requests a rebirth if it receives data for an alias that was not defined in the most recent BIRTH message. When an unknown alias is received, the mapping from alias to item is considered unreliable, so no data from the payload is processed.

A user can request a rebirth manually through the CmdDev "Command – Device" or CmdNode "Command – Edge Node" data group using the data group editor or via a UIS command. See Command-Type Data Groups for more information.

NDEATH and NBIRTH Messages

When an NDEATH or NBIRTH message is received, all device-level points mapped to data groups that are subscribed to that node will be marked as unreliable (true, if the topic is subscribed just to the node level topic or any child device-level topic of that same node) per the Sparkplug specification (section 7.1.2). NDEATH implies DDEATH for all devices on that node. Points go unreliable with a NDEATH or DDEATH message (those can be sent separately).

bdSeq Matching

The EIE supports bdSeq matching. The bdSeq is used to track the overall session of a Sparkplug client and is present in the NBIRTH and NDEATH messages. A bdSeq metric is used to match a NDEATH message (published by the MQTT Server on behalf of a disconnected Sparkplug client) with a previously published NBIRTH message to indicate the Sparkplug client is offline. This is important because the Sparkplug client might lose its connection, reconnect, and publish a new NBIRTH before the MQTT server publishes an NDEATH message from the previous session. If this happens the new NBIRTH message will contain a new bdSeq number and any subsequent NDEATH messages with old bdSeq numbers can be ignored. When a device data group receives a node birth and/or death payload, the EIE will process the messages for any bdSeq number matches, and ignore old NDEATH messages.

strictBdSeqMatch

An attribute strictBdSeqMatch is available in the root <deviceDefinition> element in the sample device template file(s) to determine how to handle NDEATH messages with respect to matched or mismatched BIRTH and NDEATH bdSeq numbers.

While the strictBdSeqMatch attribute and its default value changes how NDEATH messages are handled by the EIE, it is important to note that mismatched sequence numbers may indicate a problem and should not be ignored.

Back to top